The beautiful Magento module - MageTitans 2014

Vinai Kopp
Manchester, November 1st 2014

Introduction
Magento 1.x
2 The beautiful Magento Module November, 1st 2014

Introduction
Magento 1.x
It has contributed to the collective knowledge
of the PHP community.
Both as a good and a bad example :)

Introduction
This is not
an introduction into
Magento development.

Introduction
How can
a Magento module
be "beautiful"?

Introduction
Qualities of a beautiful module
1.It provides business value
2.Magento can be upgraded without breaking the module
3.It is easy to understand and modify
4.It has good test coverage
5.It is free of bugs

Principles and Patterns

Robert C. Martin (Uncle Bob)

Some principles and some of their fancy acronyms
•Single Responsibility Principle (SRP)
•Open Closed Principle (OCP)
•Liskov Substitution Principle (LSP)
•Interface Segregation Principle (ISP)
•Dependency Inversion Principle (DIP)

Some more principles and some more fancy acronyms
•Encapsulate what varies (ECV)
•Strive for loosely coupled designs between objects that interact (LC)
•Favor composition over inheritance (FCoI)
•Only talk to friends (LoD)
•Don't call us, we'll call you (IoC)

What have you done for
me lately, principles?

Like with all good
things in life,
there can be too much.

Open Closed Principle

“Classes should be open for extension but
closed for modification”
The Open Closed Principle
Uncle Bob

Does Magento have it?

Configuration XML merging
Often the cause of conflicts

Lets look deeper

Self-Documenting Code
Method visibility and naming

public Methods
Are an open invitation to the world

public Methods
Once published should never change
their signature or functionality

protected Methods
Communicate “override me!”

protected Methods
Change in signature or functionality
risks breaking subclasses

private Methods
Safe to change

How is method visibility used in
Magento?
Only public and protected
A too open design!

A good example of
method visibility documenting
how to extend a class.

A good example from the core how method visibility helps
abstract class Mage_Core_Block_Abstract ...
{
final public function toHtml()
{
// ...housekeeping
$html = $this->_toHtml();
// ...more housekeeping
return $html;
}
protected function _toHtml()
{
return '';
}

Another good example of OCP
Event Observers

How can we apply this principle
to our modules?
By dispatching events

Choosing strategic places to dispatch events.
Mage::dispatchEvent('events_example_import_prepare', ['importer' => $this]);
// ...
Mage::dispatchEvent(
'events_example_import_batch_start',
['importer' => $this, 'batch' => $batch]
);
// ...
Mage::dispatchEvent(
'events_example_import_batch_end',
['importer' => $this, 'batch' => $batch]);
// ...
Mage::dispatchEvent('events_example_import_complete', ['importer' => $this]);

Favor domain events over
instructional events

Choose the right method visibility
Use private as the default

Use the Magento Factory Methods
and Class Aliases

Rewrites are applied during class name resolution.
Using a Factory Method with a PHP class name
is no better then using new.
$notLikeThis = new Mage_Catalog_Model_Product();
$badExample = Mage::getModel('Mage_Catalog_Model_Product');

Rewrites are applied during class name resolution.
Using class aliases allows for rewrites.
$correctlyInstantiated = Mage::getModel('catalog/product');
gist of class name resolution steps:
http://vin.ai/class-name-resolution

To keep our code open for extension,
we should use class aliases for our classes.
$model = Mage::getModel('example_module/import_parser_xml');
$resource = Mage::getResourceModel('example_module/search');
$helper = Mage::helper('example_module');
$block = Mage::app()->getLayout()->createBlock('example_module/list');

Encapsulate what varies

“Encapsulate the Concept that Varies, i.e. a
design is better when those parts that vary
are encapsulated in a separate module”
On the Criteria To Be Used in
Decomposing Systems into Modules
David Parnas

Keep changes local so they don't
affect other parts of the system

Magento, do you ECV?

First some "missed opportunities"

Configuration of the
Tax Calculation Algorithm

Choosing the tax calculation algorithm based on the system
configuration
// from Mage_Tax_Model_Sales_Quote_Tax::collect()
switch ($this->_config->getAlgorithm($this->_store)) {
case Mage_Tax_Model_Calculation::CALC_UNIT_BASE:
$this->_unitBaseCalculation($address, $request);
break;
case Mage_Tax_Model_Calculation::CALC_ROW_BASE:
$this->_rowBaseCalculation($address, $request);
break;
case Mage_Tax_Model_Calculation::CALC_TOTAL_BASE:
$this->_totalBaseCalculation($address, $request);
break;
default:
break;
}

Order State Management

Example of sales/order state behavior management
public function canCancel()
{
if (!$this->_canVoidOrder()) {
return false;
}
if ($this->canUnhold()) { // $this->isPaymentReview()
return false;
}
// ... more of the same + comments removed for brevity...
$state = $this->getState();
if ($this->isCanceled() || $state === self::STATE_COMPLETE ||
$state === self::STATE_CLOSED) {
return false;
}
if ($this->getActionFlag(self::ACTION_FLAG_CANCEL) === false) {
return false;
}
return true;
}

Theoretical example of encapsulating the stateful behavior
class Mage_Sales_Model_Order_State_Complete implements OrderState
{
public function canInvoice()
{
return false;
}
public function canShip()
{
return false;
}
public function canReorder()
{
return true;
}
// ...

Where does the core adhere to the
principle, at least in parts?

Total Models
Total calculation
Preparation of display data

EAV Attribute Models
Backend,
Source and
Frontend models

How can we apply this principle
in our Modules?

A simple example scenario
Add information
depending on a the attribute set
to the product detail page.

A simple example scenario
Kitchen Attribute Set
Chair Attribute Set
Insurance Attribute Set

First try, not adhering to the principle
private function getTemplateForAttributeSet()
{
switch ($this->getAttributeSetId()) {
case $this->kitchenAttributeSetId:
return 'example/attributesetinfo/kitchen-info.phtml';
case $this->chairAttributeSetId:
return 'example/attributesetinfo/chair-info.phtml';
case $this->insuranceAttributeSetId:
return 'example/attributesetinfo/insurance-info.phtml';
}
}

The block also needs to provide all the methods
called from the templates
private function getTemplateForAttributeSet()
{
return 'example/attributesetinfo/kitchen-info.phtml';
return 'example/attributesetinfo/chair-info.phtml';
return 'example/attributesetinfo/insurance-info.phtml';
}
}
public function getChairCoverWashingInstructionsPDFUrl() {...}
public function getInsuranceTermsAndConditions() {...}
public function getKitchenDesignPdfUrl() {...}
public function getServicePartnerDirectoryUrl() {...}

Decomposed classes
Kitchen Attribute Set Info Block
Chair Attribute Set Info Block
Insurance Attribute Set Info Block
Attribute Set Info Block Locator

The locator extends core/text_list
class Example_AttributeSetInfo_Block_InfoBlockLocator
extends Mage_Core_Block_Text_List
{
// ...
}

Select and instantiate the delegate object
protected function _prepareLayout()
{
$infoBlockAlias = $this->_getInfoBlockClassAlias();
if (null !== $infoBlockAlias) {
$this->insert($this->_createChildBlock($infoBlockAlias));
}
}
private function _getInfoBlockClassAlias()
{
return 'example_attributesetinfo/info_kitchen';
return 'example_attributesetinfo/info_chair';
return 'example_attributesetinfo/info_insurance';
}
}

The attribute set dependent differences are encapsulated
class Example_AttributeSetInfo_Block_Info_Chair
extends Mage_Core_Block_Template
{
protected function _prepareLayout()
{
$this->setTemplate('example/attributesetinfo/chair-info.phtml');
}
public function getChairCoverWashingInstructionsPDFUrl()
{
return 'the url of the chair cover washing instructions pdf';
}
}

What would be affected by change?
What would be affected by adding an attribute set?
What would be affected if the output for one attribute set
needs to change?

More Principles

What else makes a
module beautiful?

Readable Code

Readable Code
What makes code readable?
Coding Standard

Obviously
private function getInfoBlockClassAliasBadExample () {
if ($this->getAttributeSetId()==$this->kitchenAttributeSetId)
if($this->chairAttributeSetId == $this->getAttributeSetId()) return
'example_attributesetinfo/info_chair';
else
// insurance attribute set
}
private function getInfoBlockClassAliasGoodExample()
{
return 'example_attributesetinfo/info_chair';
}
}

Readable Code
What else makes code readable?
Descriptive method names

Readable Code
How can we choose good method
names?
A method should do only one thing.
The name should state that thing.

Readable Code
If naming a method is hard split it
into smaller ones.

Readable Code
First some examples of method
names that could be improved

One bad example straight out of the Magento ORM
protected function _construct()
{
$this->_init('example_module/foo');
}

I find this would be nicer to read
protected function _initializeCollection()
{
$this->_setModelClassAlias('example_module/foo');
}

Readable Code
Methods returning a boolean value should start with is or has
public function isNewObject() {...}
public function hasChildren() {...}

Readable Code
Setters should start with set
$request->setDispatched(false)

Readable Code
Some more good bad examples

Similar methods need very descriptive names to be self documenting
// from Mage_Catalog_Model_Category
public function getChildrenCategories() {...}
public function getChildrenCategoriesWithInactive() {...}
public function getChildren() {...}
public function getAllChildren(...) {...}
public function getCategories(...) {...}

Dead code should be removed without mercy
// from Mage_Core_Model_Email
public function __construct()
{
// TODO: move to config
$this->setFromName('Magento');
$this->setFromEmail('magento@varien.com');
$this->setType('text');
}

WTF
// from Mage_Shipping_Model_Carrier_Abstract
public function getTotalNumOfBoxes($weight)
{
// ...
return $weight;
}

Wrap up

Wrap up
What qualifies a Magento module as beautiful?
1.It provides business value
2.Magento can be upgraded without breaking the module
3.It is easy to understand and modify
4.It has good test coverage
5.It is free of bugs

Further reading
Link to Amazon

Thank you

Questions | Comments
Tweet me @VinaiKopp
http://vinaikopp.com

The beautiful Magento module - MageTitans 2014

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie The beautiful Magento module - MageTitans 2014

Ähnlich wie The beautiful Magento module - MageTitans 2014 (20)

Mehr von vinaikopp

Mehr von vinaikopp (18)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

The beautiful Magento module - MageTitans 2014

Hinweis der Redaktion